The data that is contained in a grid can be grouped into logical sets through the use of GroupDescription objects. Each group description (see DataGridGroupDescription class) that is added to the GroupDescriptions collection, which is defined on the DataGridControl class, represents one group level. By changing the group descriptions contained in the GroupDescriptions collection, either programmatically or through end-user interactions with a GroupByControl (see End-User Grouping section below), group levels can be added to or removed from a grid.

<sldg:DataGridControl.GroupDescriptions>
   <sldg:DataGridGroupDescription PropertyName="ShipCountry" />
   <sldg:DataGridGroupDescription PropertyName="ShipCity" />
</sldg:DataGridControl.GroupDescriptions>

Whenever groups are created from the values of a column, those same values will automatically be sorted in ascending order; however, a SortDescription object will not be added to the SortDescriptions collection.

End-User Grouping

Through interactions with a GroupByControl, an end user can modify how the data in a grid is grouped. New groups can be created by dragging column headers into the group-by control, while existing groups can be removed by clicking the "x" that is displayed in each group-by item (see GroupByItem class). The order in which the items in a grid are grouped can also be modified by rearranging the group-by items that are currently displayed in the group-by control.

Group-by control in Signature theme

By default, a group-by control is included in the fixed header section; however, it can be removed by setting the UseDefaultHeadersFooters property, which is defined on the DataGridControl class, to false.

When the UseDefaultHeadersFooters property is set to false, all default items contained in the header and footer sections will be removed. This includes the ColumnManagerRow, whose cells are used as column headers (see ColumnManagerCell class) and through which the items in a grid can be sorted, reordered, grouped, etc. Refer to the Headers and Footers topic for additional information and examples.

A grid's AllowGroup, AllowGroupNavigation, and AllowGroupCollapsing properties can also be used to define which grouping actions an end user is permitted to do. 

Group Configurations

How a group is configured is determined by its corresponding group configuration (see DataGridGroupConfiguration class).  Group configurations are defined by group descriptions and will be used whenever groups are created from those descriptions (see also Group-Configuration Selectors section below). Through a group configuration, how the value of a group is displayed in the group headers can be modified by providing a new DataTemplate via its GroupValueTemplate property. The style that is applied to the group header can be modified by providing a new style to its GroupHeaderStyle property (see Group-Header Control Styles section below).

The code for the FlagPathConverter class can be found in the Additional Resources section of the documentation.

<sldg:DataGridGroupDescription PropertyName="ShipCountry">
    <sldg:DataGridGroupDescription.GroupConfiguration>
        <sldg:DataGridGroupConfiguration>
            <sldg:DataGridGroupConfiguration.GroupValueTemplate>
                <DataTemplate>
                    <StackPanel Orientation="Horizontal">
                        <!--The flagPathConverter resource changes the value of a
                            group (e.g., "Canada") to an image. -->
                        <Image Source="{Binding Converter={StaticResource flagPathConverter}}"
                               Margin="0, 0, 5, 0"/>
                        <TextBlock Text="{Binding}"                                                  
                                   VerticalAlignment="Center"/>
                    </StackPanel>
                </DataTemplate>
            </sldg:DataGridGroupConfiguration.GroupValueTemplate>
         </sldg:DataGridGroupConfiguration>
      </sldg:DataGridGroupDescription.GroupConfiguration>
   </sldg:DataGridGroupDescription>
<sldg:DataGridGroupDescription PropertyName="ShipCity" />

A default group configuration, which will be used for all groups whose group description does not explicitly define a group configuration, can also be provided through the DefaultGroupConfiguration property. 

Group Headers and Footers

The DataGridGroupConfiguration class exposes a collection of fixed and non-fixed (i.e., scrolling) headers and footers (see Headers, Footers, FixedHeaders, and FixedFooters properties), which represent the elements that are displayed in the headers and/or footers of every group to which the configuration is applied. Each element that is added to either collection must be added as a DataTemplate.

Elements contained in the fixed header or footer sections of a group will remain visible when the containing group is collapsed.

Each element in a group header or footer has a GroupContext, which exposes context-specific information for that element, and which is accessible through a RelativeSource the DataGridControl.GroupContext attached property. The GroupDescription property provides access to the DataGridGroupDescription that was used to create the groups, the GroupPath property exposes the DataGridPath, which represents the location of the group in a grid, while the GroupValue property exposes the group's value (e.g., "Canada", "France"). The IsBottomLevel property indicates whether the group is part of the bottom (i.e., last) level groups while the Items, ItemCount, and IsItemCountEstimated properties provide various information about the items contained in the group and their count. 

The Items and ItemCount properties will always return null (Nothing in Visual Basic) and the IsItemCountEstimated property will always return false when the grid is bound to a virtualized data source.

The GroupContext attached property will only be set on the first (i.e., root) element in the DataTemplate and can be accessed through a RelativeSource binding using the Self mode (see examples example below). Any child elements in the template can access the parent's GroupContext through an ElementName binding. For example: <TextBlock Text="{Binding ElementName=parentPanel, Path=(sldg:DataGridControl.GroupContext).GroupValue}" />

Dynamically displaying a label in group headers

The code for the LanguageToVisibilityConverter class can be found in the Additional Resources section of the documentation.

• XAML

<sldg:DataGridControl x:Name="sldgDataGridControl"
                      ItemsSource="{Binding Path=Orders}">
    <sldg:DataGridControl.Resources>
        <local:LanguageToVisibilityConverter x:Key="languageToVisibilityConverter" />
    </sldg:DataGridControl.Resources>
    <sldg:DataGridControl.GroupDescriptions>
        <sldg:DataGridGroupDescription PropertyName="ShipCountry">
            <sldg:DataGridGroupDescription.GroupConfiguration>
                <sldg:DataGridGroupConfiguration>
                    <sldg:DataGridGroupConfiguration.Headers>
                        <DataTemplate>
                            <TextBlock Text="{Binding RelativeSource={RelativeSource Self}, Path=(sldg:DataGridControl.GroupContext).GroupValue, StringFormat='{}{0} is a French-speaking country'}"
                                       Visibility="{Binding RelativeSource={RelativeSource Self}, Path=(sldg:DataGridControl.GroupContext), Converter={StaticResource languageToVisibilityConverter}}" />                   
                        </DataTemplate>
                    </sldg:DataGridGroupConfiguration.Headers>
                </sldg:DataGridGroupConfiguration>
            </sldg:DataGridGroupDescription.GroupConfiguration>
        </sldg:DataGridGroupDescription>
    </sldg:DataGridControl.GroupDescriptions>
</sldg:DataGridControl>

Adding a control to the fixed footers of a group (select all items in a group)

<sldg:DataGridControl x:Name="sldgDataGridControl"
                      ItemsSource="{Binding Path=Orders}">
   <sldg:DataGridControl.GroupDescriptions>
        <sldg:DataGridGroupDescription PropertyName="ShipCountry">
            <sldg:DataGridGroupDescription.GroupConfiguration>
                <sldg:DataGridGroupConfiguration>
                    <sldg:DataGridGroupConfiguration.FixedFooters>
                        <DataTemplate>
                            <Button Content="Select Items in Group"
                                    Click="SelectGroupItems_Click"
                                    Tag="{Binding RelativeSource={RelativeSource Self}, Path=(sldg:DataGridControl.GroupContext)}" />
                        </DataTemplate>
                    </sldg:DataGridGroupConfiguration.FixedFooters>
                </sldg:DataGridGroupConfiguration>
            </sldg:DataGridGroupDescription.GroupConfiguration>
        </sldg:DataGridGroupDescription>
    </sldg:DataGridControl.GroupDescriptions>
 
</sldg:DataGridControl>

Private Sub SelectGroupItems_Click( ByVal sender As Object, ByVal e As RoutedEventArgs )
  Dim context As  GroupContext  = CType( CType( sender, Button ).Tag, GroupContext )
 
 
 
   If Not context Is Nothing Then
      Dim propertyName As String = CType( context.GroupDescription, DataGridGroupDescription ).PropertyName
      Dim range As New SelectionRange( New SortDescription() { New SortDescription( propertyName, ListSortDirection.Ascending ) }, Nothing, Nothing )
 
 
 
      range.StartRangeInfos.Add( propertyName, context.GroupValue )
      range.EndRangeInfos.Add( propertyName, context.GroupValue )
 
 
 
      Me.sldgDataGridControl.SelectedRanges.Clear()
      Me.sldgDataGridControl.SelectedRanges.Add( range )
   End If
End Sub

private void SelectGroupItems_Click( object sender, RoutedEventArgs e )
{
   GroupContext context = ( ( Button )sender ).Tag as GroupContext;
 
 
 
   if( context != null )
   {
      string propertyName = ( ( DataGridGroupDescription )context.GroupDescription ).PropertyName;
      SelectionRange range = new SelectionRange( new SortDescription[] { new SortDescription( propertyName, ListSortDirection.Ascending ) }, null, null );
 
 
 
      range.StartRangeInfos.Add( propertyName, context.GroupValue );
      range.EndRangeInfos.Add( propertyName, context.GroupValue );
 
      this.sldgDataGridControl.SelectedRanges.Clear();
      this.sldgDataGridControl.SelectedRanges.Add( range );
   }
}

Group-Configuration Selectors

Group-configuration selectors can be used to provide specific group configurations based on various criteria. The DataGridGroupConfigurationSelector class is the abstract (MustInherit in Visual Basic) base class from which all other group-configuration selectors must derive in order to provide customized group-configuration selection criteria.

When creating a custom group-configuration selector, the Select method must be overridden to return the appropriate group configuration. Ideally, each group configuration that can be returned by the selector should be exposed as a DataGridGroupConfiguration-typed property or a collection of DataGridGroupConfiguration objects. For example, the FirstLevelGroupConfigurationSelector class is a custom group-configuration selector that provides a "special" group configuration for the first-level groups, which is exposed through the FirstLevelGroupConfiguration property. In its implementation of the Select method, if the level received is 0 (i.e., the first or "top-level" group), then the group configuration provided by the FirstLevelGroupConfiguration property is returned. For all other group levels null (Nothing in Visual Basic) is returned, indicating that the "default" group configuration should be used. 

Group-level configurations as determined by the FirstLevelGroupConfigurationSelector in Signature theme

By defining DataGridGroupConfiguration-typed properties on a custom group-configuration selector, the group configurations that can be used by a selector can be defined in XAML. For example, in the code below, the AlternatingGroupLevelConfigurationSelector class, which represents a group-configuration selector that alternates the group configurations that are applied to group levels, is defined in the resources of the grid's parent container, and the group configurations that will be applied to the even and odd group levels are defined. The alternatingGroupLevelConfigurationSelector resource is then assigned to the grid's GroupConfigurationSelector property.

The code for the AlternatingGroupLevelConfigurationSelector class can be found in the Additional Resources section of the documentation.

<!--The alternatingGroupLevelConfigurationSelector resource must be defined in the resources of the grid's
      parent container or higher.-->
 
<local:AlternatingGroupLevelConfigurationSelector x:Key="alternatingGroupLevelConfigurationSelector">
   <local:AlternatingGroupLevelConfigurationSelector.EvenGroupConfiguration>
      <sldg:DataGridGroupConfiguration>
         <sldg:DataGridGroupConfiguration.GroupHeaderStyle>
            <Style TargetType="sldg:GroupContainer">
               <Setter Property="Background"
                       Value="DeepPink"/>
            </Style>
         </sldg:DataGridGroupConfiguration.GroupHeaderStyle>
      </sldg:DataGridGroupConfiguration>
   </local:AlternatingGroupLevelConfigurationSelector.EvenGroupConfiguration>
 
   <local:AlternatingGroupLevelConfigurationSelector.OddGroupConfiguration>
      <sldg:DataGridGroupConfiguration>
         <sldg:DataGridGroupConfiguration.GroupHeaderStyle>
            <Style TargetType="sldg:GroupContainer">
               <Setter Property="Background"
                       Value="Yellow"/>
            </Style>
         </sldg:DataGridGroupConfiguration.GroupHeaderStyle>
      </sldg:DataGridGroupConfiguration>
   </local:AlternatingGroupLevelConfigurationSelector.OddGroupConfiguration>
</local:AlternatingGroupLevelConfigurationSelector>
 
 
 
<sldg:DataGridControl x:Name="sldgDataGridControl"
                      ItemsSource="{Binding Path=Orders}"
                      GroupConfigurationSelector="{StaticResource alternatingGroupLevelConfigurationSelector}">
   <sldg:DataGridControl.GroupDescriptions>
      <sldg:DataGridGroupDescription PropertyName="ShipCountry"/>
      <sldg:DataGridGroupDescription PropertyName="ShipCity" />
      <sldg:DataGridGroupDescription PropertyName="ShipVia" />
   </sldg:DataGridControl.GroupDescriptions>
</sldg:DataGridControl> 

In addition to receiving the group level, the Select method also receives the data item that has caused a new group to be created as a parameter.

The dataItem received as a parameter in the Select override of a custom group-configuration selector will always be null (Nothing in Visual Basic) in the case of a virtualized data source.

Group-Header Control Styles

Each group is encompassed within a container whose appearance can be modified by providing styles that target GroupHeaderControl. If an implicit style is provided, it will be applied to all group headers within the specified scope. Explicit styles can also be provided and assigned to a group configuration's GroupHeaderStyle property. These styles will be used whenever the group configuration is needed and will overwrite any implicit styles that may be present. 

<sldg:DataGridControl.Resources>                
   <Style TargetType="sldg:GroupHeaderControl">
      <Setter Property="BorderThickness"
              Value="2" />
      <Setter Property="BorderBrush"
              Value="DeepPink" />                    
   </Style>                               

   <Style x:Key="shipCityGroupHeaderStyle"
          TargetType="sldg:GroupHeaderControl">
      <Setter Property="BorderThickness"
              Value="2" />
      <Setter Property="BorderBrush"
              Value="Yellow" />
   </Style>
</sldg:DataGridControl.Resources>
 
 
 
<sldg:DataGridControl.GroupDescriptions>
   <sldg:DataGridGroupDescription PropertyName="ShipCountry"/>
                               
   <sldg:DataGridGroupDescription PropertyName="ShipCity">
      <sldg:DataGridGroupDescription.GroupConfiguration>
         <sldg:DataGridGroupConfiguration GroupHeaderStyle="{StaticResource shipCityGroupHeaderStyle}"/>
      </sldg:DataGridGroupDescription.GroupConfiguration>
   </sldg:DataGridGroupDescription>
</sldg:DataGridControl.GroupDescriptions>

Group-Configuration Inheritance 

Before you can fully grasp which group configuration will be used and where its property values will be retrieved from, it is important to first understand the inheritance hierarchy.  Group configurations can be provided:

• Per group description (see DataGridGroupDescription.GroupConfiguration property) 
• Per column through its attached group description  (see Column.GroupDescription property)
• By a group-configuration selector (see DataGridControl.GroupConfigurationSelector property)
• As the default group configuration when explicit configurations are not provided (see DataGridControl.DefaultGroupConfiguration property)

A group configuration exposes the GroupValueTemplate and the GroupHeaderStyle whose values, when not explicitly set, will be inherited from any implicit styles or a group configurations returned by a group-configuration selector.

Let's take the example of a group description's group configuration whose GroupValueTemplate has been explicitly set but that does not explicitly provide a value for its GroupHeaderStyle property. In this situation, if an implicit group-header style is accessible, it will be used; however, if a group-configuration selector is also present and returns a corresponding group configuration that defines a group-header style, then the values of the explicitly defined group configuration and the values of the group configuration returned by the selector will be "merged". In other words, the resulting groups will use the group-value template from the explicitly defined group configuration as well as the group-header style returned by the selector (see #1 in the diagram below). Of course, if the group-value template and the group-header style were both explicitly defined on the group description's group configuration, the values returned by the selector would be ignored (see #2 in the diagram below).

Some themes, such as the Signature, Metro, and Live Explorer themes, contain implicit styles that target DataGridControl and define a "default" group-configuration selector. In order to prevent the values returned by the selector from being inherited by group configurations, the GroupConfigurationSelector property defined by the DataGridControl class can  be set to null (Nothing in Visual Basic) or a new selector can be provided (see #3 in the diagram below). This means that if a theme that defines a group-configuration selector is used and a default group configuration is provided through the DefaultGroupConfiguration property, the default group configuration will be ignored, usually only for first-level groups.

Below is a nifty diagram that attempts to illustrate what is described in the paragraph above:

Column-Specific Group Descriptions

Group descriptions have a limited lifespan within the GroupDescriptions collection, meaning that once they are removed, only a new instance can take its place. The GroupDescription property, which is defined on the Column class, resolves this issue by allowing you to specify the group description that will be used whenever the data in a grid is grouped by the values of that column. 

<sldg:DataGridControl.Columns>
   <sldg:Column FieldName="ShipCountry"
                Title="Country">
      <sldg:Column.GroupDescription>
         <sldg:DataGridGroupDescription PropertyName="ShipCountry">
            <sldg:DataGridGroupDescription.GroupConfiguration>
               <sldg:DataGridGroupConfiguration>
                  <sldg:DataGridGroupConfiguration.GroupHeaderStyle>
                     <Style TargetType="sldg:GroupContainer">
                        <Setter Property="BorderThickness" Value="2" />
                        <Setter Property="BorderBrush" Value="DeepPink" />
                     </Style>
                  </sldg:DataGridGroupConfiguration.GroupHeaderStyle>
               </sldg:DataGridGroupConfiguration>
            </sldg:DataGridGroupDescription.GroupConfiguration>
         </sldg:DataGridGroupDescription>
      </sldg:Column.GroupDescription>
   </sldg:Column>
</sldg:DataGridControl.Columns>

Group-Navigation Controls

The group-navigation controls, which are displayed in the group headers, allow quick navigation between same-level groups by entering the name of the group to which to jump or by pressing on the up and down arrows to navigate to the previous or next groups, respectively.

Group-navigation controls in Signature theme

If and which group-navigation controls are displayed depends on the values of the AllowGroupNavigation property and GroupNavigationModes properties. The AllowGroupNavigation property, which is defined on both the DataGridControl and DataGridGroupConfiguration classes, determines if all group-navigation controls are to be hidden. If set to false on the grid, all group-navigation controls will be hidden. If set to false on a group-configuration, the group-navigation controls will be hidden only for the groups that are based on the group configuration. The GroupNavigationModes property, which works in association with the AllowGroupNavigation property determines which of the group-navigation controls are displayed.

<sldg:DataGridControl x:Name="sldgDataGridControl"                             
                      ItemsSource="{Binding Path=Orders}"
                      AllowGroupNavigation="False">
    <sldg:DataGridControl.Resources>
        <sldg:DataGridGroupConfiguration x:Key="navigableGroupConfiguration" 
                                         AllowGroupNavigation="True"/>
    </sldg:DataGridControl.Resources>
 
    <sldg:DataGridControl.GroupDescriptions>
        <sldg:DataGridGroupDescription PropertyName="ShipCountry"
                                       GroupConfiguration="{StaticResource navigableGroupConfiguration}"/>
        <sldg:DataGridGroupDescription PropertyName="ShipCity"/>
    </sldg:DataGridControl.GroupDescriptions>
 
    <sldg:DataGridControl.Columns>
        <sldg:Column FieldName="ShipCountry">
            <sldg:Column.GroupDescription>
                <sldg:DataGridGroupDescription PropertyName="ShipCountry"
                                            GroupConfiguration="{StaticResource navigableGroupConfiguration}"/>
            </sldg:Column.GroupDescription>
        </sldg:Column>
    </sldg:DataGridControl.Columns>
</sldg:DataGridControl>

Collection-Changed Notifications

The GroupDescriptions collection is an ObservableCollection, which means that in order to receive notifications as to when its items change (i.e., group descriptions are added or removed), you can subscribe to its CollectionChanged event. The CollectionChanged event will be raised once for each group description that is added or removed, either programmatically or through the GroupByControl.

Public Sub New()
   InitializeComponent()

 
   AddHandler sldgDataGridControl.GroupDescriptions.CollectionChanged, AddressOf GroupDescriptions_CollectionChanged
End Sub

Private Sub GroupDescriptions_CollectionChanged(ByVal sender As Object, ByVal e As System.Collections.Specialized.NotifyCollectionChangedEventArgs)
   Debug.WriteLine("Group Descriptions Changed")
End Sub

public MainPage()
{
   InitializeComponent();

 
   sldgDataGridControl.GroupDescriptions.CollectionChanged += new System.Collections.Specialized.NotifyCollectionChangedEventHandler(GroupDescriptions_CollectionChanged);
}

void GroupDescriptions_CollectionChanged(object sender, System.Collections.Specialized.NotifyCollectionChangedEventArgs e)
{
   Debug.WriteLine("Group Descriptions Changed");
}